Eclipse Platform
Pre-release 3.0

org.eclipse.ui.application
Class WorkbenchAdvisor

java.lang.Object
  extended byorg.eclipse.ui.application.WorkbenchAdvisor

public abstract class WorkbenchAdvisor
extends Object

Public base class for configuring the workbench.

Note that the workbench advisor object is created in advance of creating the workbench. However, by the time the workbench starts calling methods on this class, PlatformUI.getWorkbench is guaranteed to have been properly initialized.

Example of creating and running a workbench (in an IPlatformRunnable):

 
 public class MyApplication implements IPlatformRunnable {
   public Object run(Object args) {
     WorkbenchAdvisor workbenchAdvisor = new MyWorkbenchAdvisor();
     Display display = PlatformUI.createDisplay();
     int returnCode = PlatformUI.createAndRunWorkbench(display, workbenchAdvisor);
     if (returnCode == PlatformUI.RETURN_RESTART) {
        return IPlatformRunnable.EXIT_RESTART;
     } else {
        return IPlatformRunnable.EXIT_OK;
   }
 }
 
 

An application should declare a subclass of WorkbenchAdvisor and override methods to configure the workbench to suit the needs of the particular application.

The following advisor methods are called at strategic points in the workbench's lifecycle (all occur within the dynamic scope of the call to PlatformUI.createAndRunWorkbench):

Since:
3.0

Field Summary
static int FILL_MENU_BAR
          Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's menu bar.
static int FILL_PROXY
          Bit flag for fillActionBars indicating that the operation is not filling the action bars of an actual workbench window, but rather a proxy (used for perspective customization).
static int FILL_STATUS_LINE
          Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's status line.
static int FILL_TOOL_BAR
          Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's tool bar.
 
Constructor Summary
protected WorkbenchAdvisor()
          Creates and initializes a new workbench advisor instance.
 
Method Summary
 void eventLoopException(Throwable exception)
          Performs arbitrary actions when the event loop crashes (the code that handles a UI event throws an exception that is not caught).
 void eventLoopIdle(Display display)
          Performs arbitrary work or yields when there are no events to be processed.
 void fillActionBars(IWorkbenchWindow window, IActionBarConfigurer configurer, int flags)
          Configures the action bars using the given action bar configurer.
 IAdaptable getDefaultPageInput()
          Returns the default input for newly created workbench pages.
 IAdaptable getDefaultWindowInput()
          Deprecated. This method has been renamed getDefaultPageInput. It has been marked final as advanced wiarning, and will be removed entirely by M7.
abstract  String getInitialWindowPerspectiveId()
          Returns the id of the initial perspective for new workbench windows.
 String getMainPreferencePageId()
          Returns the id of the preference page that should be presented most prominently.
 void initialize(IWorkbenchConfigurer configurer)
          Performs arbitrary initialization before the workbench starts running.
 boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer, String menuId)
          Returns whether the menu with the given id is an application menu of the given window.
 void postRestore()
          Performs arbitrary actions after the workbench and its windows have been restored, but before the main event loop is run.
 void postShutdown()
          Performs arbitrary finalization after the workbench stops running.
 void postStartup()
          Performs arbitrary actions after the workbench windows have been opened (or restored), but before the main event loop is run.
 void postWindowClose(IWorkbenchWindowConfigurer configurer)
          Performs arbitrary actions after the given workbench window is closed.
 void postWindowOpen(IWorkbenchWindowConfigurer configurer)
          Performs arbitrary actions after the given workbench window has been opened (possibly after being restored).
 void postWindowRestore(IWorkbenchWindowConfigurer configurer)
          Performs arbitrary actions after the given workbench window has been restored, but before it is opened.
 void preShutdown()
          Performs arbitrary finalization before the workbench is about to shut down.
 void preStartup()
          Performs arbitrary actions just before the first workbench window is opened (or restored).
 void preWindowOpen(IWorkbenchWindowConfigurer configurer)
          Performs arbitrary actions before the given workbench window is opened.
 boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
          Performs arbitrary actions as the given workbench window's shell is being closed directly, and possibly veto the close.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FILL_PROXY

public static final int FILL_PROXY
Bit flag for fillActionBars indicating that the operation is not filling the action bars of an actual workbench window, but rather a proxy (used for perspective customization).

See Also:
Constant Field Values

FILL_MENU_BAR

public static final int FILL_MENU_BAR
Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's menu bar.

See Also:
Constant Field Values

FILL_TOOL_BAR

public static final int FILL_TOOL_BAR
Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's tool bar.

See Also:
Constant Field Values

FILL_STATUS_LINE

public static final int FILL_STATUS_LINE
Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's status line.

See Also:
Constant Field Values
Constructor Detail

WorkbenchAdvisor

protected WorkbenchAdvisor()
Creates and initializes a new workbench advisor instance.

Method Detail

initialize

public void initialize(IWorkbenchConfigurer configurer)
Performs arbitrary initialization before the workbench starts running.

This method is called during workbench initialization prior to any windows being opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench, and hang on to the configurer if further tweaking may be required in the future.

Parameters:
configurer - an object for configuring the workbench

preStartup

public void preStartup()
Performs arbitrary actions just before the first workbench window is opened (or restored).

This method is called after the workbench has been initialized and just before the first window is about to be opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.


postStartup

public void postStartup()
Performs arbitrary actions after the workbench windows have been opened (or restored), but before the main event loop is run.

This method is called just after the windows have been opened. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. It is okay to IWorkbench.close() from this method.


postRestore

public void postRestore()
Performs arbitrary actions after the workbench and its windows have been restored, but before the main event loop is run.

This method is called after previously-saved windows have been recreated, and before postStartup. This method is not called when the workbench is started for the very first time, or if workbench state is not saved or restored. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. It is okay to IWorkbench.close() from this method.


preShutdown

public void preShutdown()
Performs arbitrary finalization before the workbench is about to shut down.

This method is called immediately prior to workbench shutdown before any windows have been closed. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.


postShutdown

public void postShutdown()
Performs arbitrary finalization after the workbench stops running.

This method is called during workbench shutdown after all windows have been closed. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.


eventLoopException

public void eventLoopException(Throwable exception)
Performs arbitrary actions when the event loop crashes (the code that handles a UI event throws an exception that is not caught).

This method is called when the code handling a UI event throws an exception. In a perfectly functioning application, this method would never be called. In practice, it comes into play when there is bugs in the code that trigger unchecked runtime exceptions. It is also activated when the system runs short of memory, etc. Fatal errors (ThreadDeath) are not passed on to this method, as there is nothing that could be done.

Clients must not call this method directly (although super calls are okay). The default implementation logs the problem so that it does not go unnoticed. Subclasses may override or extend this method. It is generally a bad idea to override with an empty method, and you should be especially careful when handling Errors.

Parameters:
exception - the uncaught exception that was thrown inside the UI event loop

eventLoopIdle

public void eventLoopIdle(Display display)
Performs arbitrary work or yields when there are no events to be processed.

This method is called when there are currently no more events on the queue to be processed at the moment.

Clients must not call this method directly (although super calls are okay). The default implementation yields until new events enter the queue. Subclasses may override or extend this method. It is generally a bad idea to override with an empty method. It is okay to call IWorkbench.close() from this method.

Parameters:
display - the main display of the workbench UI

preWindowOpen

public void preWindowOpen(IWorkbenchWindowConfigurer configurer)
Performs arbitrary actions before the given workbench window is opened.

This method is called before the window's controls have been created. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench window in an application-specific way; however, filling the window's menu bar, tool bar, and status line must be done in fillActionBars, which is called immediately after this method is called.

Parameters:
configurer - an object for configuring the particular workbench window being opened

fillActionBars

public void fillActionBars(IWorkbenchWindow window,
                           IActionBarConfigurer configurer,
                           int flags)
Configures the action bars using the given action bar configurer. Under normal circumstances, flags does not include FILL_PROXY, meaning this is a request to fill the actions\ bars of the given workbench window; the remaining flags indicate which combination of the menu bar (FILL_MENU_BAR), the tool bar (FILL_TOOL_BAR), and the status line (FILL_STATUS_LINE) are to be filled.

If flags does include FILL_PROXY, then this is a request to describe the actions bars of the given workbench window (which will already have been filled); again, the remaining flags indicate which combination of the menu bar, the tool bar, and the status line are to be described. The actions included in the proxy action bars can be the same instances as in the actual window's action bars. Calling ActionFactory to create new action instances it is not recommended, because these actions interally register listeners with the window and there is no opportunity to dispose of these actions.

This method is called just after preWindowOpen. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.

Parameters:
window - the workbench window
configurer - the action bar configurer object
flags - bit mask composed from the constants FILL_MENU_BAR, FILL_TOOL_BAR, FILL_STATUS_LINE, and FILL_PROXY

postWindowRestore

public void postWindowRestore(IWorkbenchWindowConfigurer configurer)
                       throws WorkbenchException
Performs arbitrary actions after the given workbench window has been restored, but before it is opened.

This method is called after a previously-saved window have been recreated. This method is not called when a new window is created from scratch. This method is never called when a workbench is started for the very first time, or when workbench state is not saved or restored. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. It is okay to IWorkbench.close() from this method.

Parameters:
configurer - an object for configuring the particular workbench window just restored
Throws:
WorkbenchException

postWindowOpen

public void postWindowOpen(IWorkbenchWindowConfigurer configurer)
Performs arbitrary actions after the given workbench window has been opened (possibly after being restored).

This method is called after a window have been opened. This method is called after a new window has been created from scratch, or when a previously-saved window has been restored. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override.

Parameters:
configurer - an object for configuring the particular workbench window just opened

preWindowShellClose

public boolean preWindowShellClose(IWorkbenchWindowConfigurer configurer)
Performs arbitrary actions as the given workbench window's shell is being closed directly, and possibly veto the close.

This method is called from a ShellListener associated with the workbench window. It is not called when the window is being closed for other reasons. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients may use the configurer passed in to access the workbench window being closed. If this method returns false, then the user's request to close the shell is ignored. This gives the workbench advisor an opportunity to query the user and/or veto the closing of a window under some circumstances.

Parameters:
configurer - an object for configuring the particular workbench window whose shell is being closed
Returns:
true to allow the window to close, and false to prevent the window from closing
See Also:
IWorkbenchWindow.close()

postWindowClose

public void postWindowClose(IWorkbenchWindowConfigurer configurer)
Performs arbitrary actions after the given workbench window is closed.

This method is called after the window's controls have been disposed. Clients must not call this method directly (although super calls are okay). The default implementation does nothing. Subclasses may override. Typical clients will use the configurer passed in to tweak the workbench window in an application-specific way.

Parameters:
configurer - an object for configuring the particular workbench window being closed

isApplicationMenu

public boolean isApplicationMenu(IWorkbenchWindowConfigurer configurer,
                                 String menuId)
Returns whether the menu with the given id is an application menu of the given window. This is used during OLE "in place" editing. Application menus should be preserved during menu merging. All other menus may be removed from the window.

The default implementation returns false. Subclasses may override.

Parameters:
configurer - an object for configuring the workbench window
menuId - the menu id
Returns:
true for application menus, and false for part-specific menus

getDefaultWindowInput

public final IAdaptable getDefaultWindowInput()
Deprecated. This method has been renamed getDefaultPageInput. It has been marked final as advanced wiarning, and will be removed entirely by M7.

Returns the default input for newly created workbench pages.

The default implementation returns null. Subclasses may override.

Returns:
the default input for a new workbench window page, or null if none

getDefaultPageInput

public IAdaptable getDefaultPageInput()
Returns the default input for newly created workbench pages.

The default implementation returns null. Subclasses may override.

Returns:
the default input for a new workbench window page, or null if none

getInitialWindowPerspectiveId

public abstract String getInitialWindowPerspectiveId()
Returns the id of the initial perspective for new workbench windows.

This method is called during startup when the workbench is restoring the window(s) or creating a new window. Subclasses must implement.

Returns:
the id of the initial perspective

getMainPreferencePageId

public String getMainPreferencePageId()
Returns the id of the preference page that should be presented most prominently.

The default implementation returns null. Subclasses may override.

Returns:
the id of the preference page, or null if none

Eclipse Platform
Pre-release 3.0

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.